GEM Menus with Lattice C

Steve Ollett orders the most expensive item on the menu!

The purpose of this guide is to explain how GEM menus can be created and used in your own C programs, and assumes that you will know at least the fundamentals of C.  If not, there are plenty of guides available to teach this, not only on the internet, but from your local library.

I have used Lattice C5.60 (including the WERCS - Windows Environment Resource Construction Program) for this program, but it should work on the Alycon Compiler (freely available from the FREEGEM Webring) and Pure C without much trouble.

The program was written on my PC while using Gemulator 2000 (freely available from Emulators Inc.) and has been tested on my own TOS 1.62 ATARI STE, and *should* work on any ST, however, I would like to point out that the attached code/listings is to be used at your own risk and I cannot be held responsible for any data loss, sleepless nights or natural disasters arising from its usage.

If the text in this guide appears to be a bit patronising, I apologise - but I would rather explain things as clearly and basically as possible so that people can grasp the fundamentals, and then experiment for themselves at a later date.

TESTMENU - What's included?

Included in the download file are the following:

Test the program

If you want to see what the finished program is like, then run TESTMENU.PRG. Make sure that TESTMENU.RSC is in the same directory or you'll get an error dialog.

Starting from scratch

A good way to understand something is to start at the beginning and work through it. So that's what we'll do with TESTMENU.

First, lets create a folder on our harddrive where we will save our files. Lets call it TESTMENU.

Design our menu

We'll design a menu with the following features:-

NOTE: Only the contents of the first 2 columns will appear on our finished menu, the other two columns inform us of what they will do, and their ID Name which we will use in the main C Code when checking if an option has been selected or not.

Create menu with WERCS

1. Run LC5.PRG, Select 'WERCS' from 'Tools' option on the menu bar. Click [OK] or press [RETURN] to enter WERCS.
2. Select 'Languages' From 'File' Option on menu bar.
3. Select Radio Boxes 'C' & 'Mixed' then click [OK] or press [RETURN].
4. Select 'Save Prefs' from 'File' on menu bar to save settings made in (3.)
5. A Resource File is like an upside-down tree with smaller elements branching off like, erm, branches. WERCS uses this idea of the resource tree, and to start making our menu, from 'Tree' on the menu bar, select 'Menu' to create our menu.
6. A Dialog, titled æName of TreeÆ will appear asking for a name to be entered for the menu we are creating. Press [ESCAPE] and type in æmenu1Æ(without the quotes). We could have put in almost any name really, but whatever the identifier name is used, the case of the name should be kept constant or our C program will not be able to find our menu!
7. Click on EDIT to edit our new menu.
8. To rename 'Desk' to show our Fuji (/|\), double click on 'Desk'. Where it says 'Text:' on the dialog, press [SPACE] then [CONTROL]+[N], then [CONTROL]+[O] to get our Fuji, then [SPACE] and press [RETURN]. We put in the spaces there so that the menu title is not running into the start of our next menu title.
9. With the Fuji Option opened, you'll see a line of text saying æYour message hereÆ. Double Click on that line of text, clear the text by pressing [ESCAPE] and enter ' About TESTMENU...' (without the quotes). Notice that we have put two blank spaces before the text and three æ.Æs after the text.
   
   This is the convention for creating menus as the extra space is required so that if a æCheckÆ (or ætickÆ if youÆre British) if used then the whole thing looks nicer if itÆs spaced out properly. The three periods (or fullstops if youÆre British) means that a dialog or alert will follow if this option is selected. Also, if we leave at least One space after the entry that makes it look nicer too.
   
   Tab to the next option marked ænameÆ and enter our identifier name æmaboutÆ (all lower case, without the quotes) from our table listed previously in this guide. Press [RETURN]. OK! First part done!
10. Goto the æFileÆ Option on our new menu. Double Click on æQuitÆ. Enter æmquitÆ as the identifier name. Press [RETURN]
11. From æObjectÆ on WERCS menu bar, select æStringÆ. The mouse pointer will change to a small rectangle. Move the pointer until it is over the æQuitÆ entry, but to left of it, while still inside the rectangleÆs boarder line. Left Click and a new entry called æSTRINGÆ will be inserted. Double Left Click on æSTRINGÆ. Change the text to read æ Close æ (include spaces). Enter the name as æmcloseÆ.
12. Follow No.11 in this guide for the æOpenÆ option and the divider line.
    
    Note - the divider line needs to have one spaces in front of and behind it. Also, when you have created the divider line, click on it once so that it is highlighted, then select ædisabledÆ from the WERCS æFlagsÆ menu so that it appearance is ghosted and cannot be selected when in your compiled program.
    
    When inserting a string click the mouse pointer over the item you want your string to be inserted above, for example over the æCloseÆ entry.
13. Okay, after creating the options for the file menu, now we create the other options. From æObjectÆ on WERCS menubar, select æTitleÆ. The mouse arrow will change to show a small æTITLEÆ symbol. Move the mouse until its on the menu bar you are creating and Left Click the mouse button.
    Double Left Click on æTITLEÆ and rename as æOptionsÆ
14. Follow the above instructions and enter the other options, including the identifier names as set out in our table.
15. When all is done, goto æFileÆ on WERCS menu bar and æSave AsÆ TESTMENU.RSC, making sure that it is to our TESTMENU directory.

TESTMENU - The C code

I have included the code for TESTMENU so that it doesnÆt require re-typing and that you can make whatever amendments you see fit. When you compile the files, make sure that they are all in the same directory so that nothing goes wrong.

TESTMENU - Compile with Lattice C 5.60

1. Run LC5.PRG
2. 2. Load TESTMENU.C from æFileÆ
3. From æProjectÆ on menu bar, load æTESTMENU.PRJÆ
   
   If you donÆt have the *.PRJ file, or you want to set up Lattice to compile for yourself, then do the following:-
   
   
   1. Under æProjectÆ, select æNew...Æ and type in æTESTMENU.PRJÆ and press [RETURN].
   2. Under æProjectÆ, select æEdit "TESTMENU"...Æ which opens the æProject ManagementÆ dialog.
   3. Under the box labelled æInput FilesÆ, click on æAddÆ, and using the fileselector, locate æTESTMENU.CÆ, click on it and press [RETURN].
   4. æTESTMENU.CÆ should now be inside the æInput filesÆ box, and while it is still highlighted, click on æAddÆ, this time in the æDependent filesÆ box. Locate æTESTMENU.HÆ (Your header file for the resource file made earlier with WERCS) and click on it and press [RETURN].
   5. Press [RETURN] or click on [OK] at bottom right of æProject Management dialogÆ.
   6. Under æOptionsÆ on menubar, move mouse pointer over æCompilerÆ and go across to submenu. Click on æGeneralÆ to open a dialog. Click on box for æDefault short integersÆ (as we are only dealing with small numbers in our program code), and click [OK} or press [RETURN].
   7. Select æEXECUTABLE..Æ from æOptionsÆ on menubar. Click on æBuild GEM applicationÆ box and click on [OK] or press [RETURN].
   8. Finally, under æProjectÆ on menu bar, click on æSave "TESTMENU"Æ to save the settings just made.

1. To compile and run your program, select æRun "TESTMENU"Æ from æProjectÆ on the menu bar. Lattice should now put a new window on the screen as it compiles and links the program code into a *.PRG file, named the same as the project file - in this case it will be TESTMENU.PRG. if all goes well, there shouldnÆt be any error messages and Lattice will run TESTMENU.
   
   You can then try out all of the functions. Select æQuitÆ to close the program.

TESTMENU - C code explained (I hope!)

Okay, so IÆm not an expert, but I hope it gives you a bit of an idea of what is going on. As IÆve no doubt said before, the best way to learn is to alter the example code and see what happens.

As for me, IÆll take a deserved rest until next time.

Steve Ollett

MyAtari magazine - Tutorial #1, March 2001